Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

CHAPTER 2
Work Habits

This chapter discusses specific work habits and programming techniques you can use to make bug management easier. Simple practices, like keeping a bug log and working when you are most alert, can reduce the number of bugs in your code and allow you to find and repair the bugs that do occur more easily.

Keep a Notebook

As much as some managers might wish to believe programming is a simple construction task like building a brick wall, it is not. Programming is an experimental laboratory science. It includes plenty of theoretical research, too, but real programs must work in the real world, not just in theory. Programs are carefully designed using the latest tools and techniques, but in the end, trial and error plays an important role in all but the simplest applications.

Scientists in other experimental fields keep laboratory notebooks and programmers should too. Things you should put in the notebook include

•  Decisions made at project meetings

•  Other meeting notes

•  Phone numbers of customers, vendors, etc.

•  Notes made during phone calls

•  Initial doodlings while you think about programming ideas

•  Diagrams and flow charts of algorithms you may need

•  References to journals and books in which you find something useful

•  Timing results when you test different algorithms

•  Bug descriptions and fixes

•  Lists of things to do later

When I start a new major project, I start a new notebook. Usually I take 50 to 100 pages of notes during the course of the project, not including notes I keep online in the form of email and other electronic documentation. After I write something down, I almost never need to look at it again. A few times each month, however, I need to look up some little detail that I have forgotten. This is particularly helpful with obscure bugs that I only rarely encounter. The notebook lets me look up the bug and its solution in just minutes, instead of wasting hours trying to recreate the solution.

Physical and online notebooks each have their advantages. You can take physical notebooks to meetings, draw freehand flow charts and data flow diagrams in them, and tape journal articles in them. Online notebooks can be searched, are easy to cut and paste into documentation, and are easy to email to other developers.

I usually use a combination of both systems. If something is easy to enter online, like a bug description, I email it to myself and store it in a special project email folder. If it is hard to store electronically, like diagrams or meeting notes, I put it in my notebook.

Keep a Bug Log

A bug log is one of the most important parts of your notebook. Quickly finding information about previously encountered bugs can save you hours of effort.

One useful technique is to email bug information to yourself. Put descriptive information in the message’s subject so you can search for the report later. File the message in a bugs mail folder. In the message, you should note

Description. What is the bug?

Cause. What caused the bug? Is this a symptom of a larger bug?

Symptoms. How can you tell if the bug is present?

Cure. How did you fix this bug?

Prevention. How could this bug have been prevented?

Detection. How can similar bugs be detected automatically?

If your project uses a shared bug log, you can learn from errors found by other developers. To create a shared bug repository, create a special user named Bugs. When you send yourself a bug note, send a copy to Bugs. Later, if you need to find a bug report, you can log on as Bugs and search everyone’s bug messages.

Analyze the Bug Log

When your project is finished, analyze the bug log to learn from past mistakes. See which bugs caused the greatest trouble for the most developers and focus on them. Discuss new methods that the team can use to detect and correct bugs earlier than they did in this project.

Pay particular attention to bugs that remained undetected for a long time. Those bugs tend to cause the most mischief so it is worth some extra effort to prevent them in the future. Determine when each bug was introduced and spend additional time discussing ways to avoid bugs that occur early in the development cycle.

Note which phases may need improvement. If many bugs were introduced during the program’s high-level design phase, you should probably spend more time on that phase in future projects.

It is also worth noting which developers created the most errors and during which phases of the project. Be careful that this does not become a hunt for scapegoats, but it may indicate which developers could use extra training in a particular aspect of development. For example, you may find one programmer who introduced more than his share of bugs into the database management code. That programmer might benefit from some extra database management courses.

Save Everything

Save everything you receive that relates to the project, no matter how trivial it seems. Keep every email and memo you receive. Take notes during meetings, conversations, and phone calls. If important decisions are made, type the notes up and email them to yourself and to the others involved in the decision.

The amount of material you save will start to add up, but it should cost you very little to keep it until the end of the project. In some of the projects I have worked on, the amount of historical data added up to a few megabytes of disk space and a few thousand pages of printed text. It easily fit on one backup tape and in a single storage box.

You may never need to access most of this information, but once in a great while it can save you hours of frustration. In several of the projects I have worked on, a customer reopened an issue that had been closed earlier in the development process. By quickly retrieving the old memos and emails that had resolved the issue before, we were able to reevaluate the problem and get back to work on new issues with little wasted time.

In some projects we created an account named History. Every project member sent copies of meeting notes, conversation notes, and memos to this account. On those infrequent occasions when two developers disagreed on a customer request, they could refer to the history email to learn exactly what was said and when without bothering the customer over a closed issue.